/**
 * http://code.google.com/p/gwt-spot
 * 
 * GWT-Spot -- Copyright 2008-2009
 *          -- by Dunkel, Ricardo
 *  
 */
package de.ricardodunkel.gwtspot.client.api.ui.common;

import com.google.gwt.user.client.ui.CheckBox;
import com.google.gwt.user.client.ui.RadioButton;
import com.google.gwt.user.client.ui.SuggestBox;
import com.google.gwt.user.client.ui.SuggestOracle;
import com.google.gwt.user.client.ui.TextArea;
import com.google.gwt.user.client.ui.TextBox;
import com.google.gwt.user.client.ui.Widget;

/**
 * Common form utility class for comfortable object handling.
 * 
 * <p>
 * 	Form elements are representing user input fields usually.
 *  To enable an easy <em>one line</em> creation, we have 
 *  defined several helper functions.
 * </p>
 * <p> 
 *  Further on, they are overloaded multiple times and provide 
 *  a common usage this way.
 * </p>
 * 
 * @author Dunkel, Ricardo
 * 
 * @version 0.1
 * 
 */
public class FormUtility extends WidgetUtility {

	// -------------------------- TEXTBOX SECTION -----------------------------
	/**
	 * Does create a <em>minimum</em> {@link TextBox}.
	 * 
	 * @param title  A title used for creation of {@link TextBox}, may be null but should not.
	 * 
	 * @return A desired {@link TextBox} widget.
	 */
	public static TextBox createTextBox( String title ) {
		return createTextBox(title, null);
	}
	
	/**
	 * Does create a <em>basic</em> {@link TextBox}.
	 * 
	 * @param title  A title used for creation of {@link TextBox}, may be null but should not.
	 * @param text  A text to set for element description, may be null.
	 * 
	 * @return A desired {@link TextBox} widget.
	 */
	public static TextBox createTextBox( String title, String text ) {
		return createTextBox(title, null, null);	
	}
	
	/**
	 * Does create a <em>full qualified</em> {@link TextBox}.
	 * 
	 * @param title  A title used for creation of {@link TextBox}, may be null but should not.
	 * @param text  A text to set for element description, may be null.
	 * @param style  A style which may used for element, may be null.
	 * 
	 * @return A desired {@link TextBox} widget.
	 */
	public static TextBox createTextBox( String title, String text, String style ) {
		TextBox tb = new TextBox();
		setWidgetProperties(tb, title, style);
		setWidgetText( tb, text );
		return tb;
	}
	
	// -------------------------- TEXTAREA SECTION ----------------------------
	/**
	 * Does create a new {@link TextArea} element.
	 * 
	 * @param text  A text to set for element description.
	 * @param style  A style which may used for element.
	 * @param enabled  Indicates weather or not an area is enabled or not.
	 * @param readonly  Indicates <em>read-only</em> input state for element.
	 * 
	 * @return  A text area which does fit to incoming parameters.
	 */
	public static TextArea createTextArea(String style, String text, boolean enabled, boolean readonly) {
		TextArea txt = new TextArea();
		txt.setStyleName( style );
		txt.setText( text );
		txt.setEnabled( enabled );
		txt.setReadOnly( readonly );
		return txt;
	}

	// -------------------------- SUGGEST SECTION -----------------------------
	/**
	 *  Does create a <em>basic</em> {@link SuggestBox}.
	 * 
	 * @param A title used for creation of {@link SuggestBox}.
	 * @param oracle  An oracle used for initialization.
	 * 
	 * @return  A {@link SuggestBox} widget.
	 */
	public static Widget createSuggestBox(String title, SuggestOracle oracle) {
		return createSuggestBox(title, title, null, oracle);
	}
	
	/**
	 * Does create a <em>full qualified</em> {@link SuggestBox}.
	 * 
	 * @param title  A title used for creation of {@link SuggestBox}.
	 * @param text  A text used for creation of {@link SuggestBox}.
	 * @param style  A style used for creation of {@link SuggestBox}.
	 * @param oracle  An oracle used for initialization.
	 * 
	 * @return  A {@link SuggestBox} widget.
	 */
	public static SuggestBox createSuggestBox(String title, String text, String style, SuggestOracle oracle) {
		SuggestBox t = new SuggestBox(oracle);
		setWidgetProperties(t, title, style);
		setWidgetText( t, text );
		t.setAnimationEnabled(true);
		return t;
	}
	
	// -------------------------- CHECKBOX SECTION ----------------------------
	/**
	 * Does create a <em>minimum</em> {@link CheckBox}.
	 * 
	 * @param title  A title used for creation of {@link CheckBox}, may be null but should not.
	 * 
	 * @return A desired {@link CheckBox} widget.
	 */
	public static Widget createCheckBox(String title) {
		return createCheckBox(title, null, null);
	}
	
	/**
	 * Does create a <em>basic</em> {@link CheckBox}.
	 * 
	 * @param title  A title used for creation of {@link CheckBox}, may be null but should not.
	 * @param text  A text to set for element description, may be null.
	 * 
	 * @return A desired {@link CheckBox} widget.
	 */
	public static Widget createCheckBox(String title, String text) {
		return createCheckBox(title, text, null);
	}

	/**
	 * Does create a {@link CheckBox} with default check state.
	 * 
	 * @param text  A text to set for element description, may be null.
	 * @param checked  Indicates standard state of box.
	 * 
	 * @return  A <em>checked</em> or <em>unchecked</em> box element.
	 */
	public static Widget createCheckBox(String text, boolean checked) {
		return createCheckBox(text, text, null, checked, true);
	}
	
	/**
	 * Does create a {@link CheckBox} with default check state and activation.
	 * 
	 * @param text  A text to set for element description, may be null.
	 * @param checked  Indicates standard state of box.
	 * @param enabled  Indicates weather or not a box is enabled after creation.
	 * 
	 * @return  A box which fits desired parameters.
	 */
	public static Widget createCheckBox(String text, boolean checked, boolean enabled) {
		return createCheckBox(text, text, null, checked, enabled);
	}
	
	/**
	 * Does create an <em>extended</em> {@link CheckBox}.
	 * 
	 * @param title  A title used for creation of {@link CheckBox}, may be null but should not.
	 * @param text  A text to set for element description, may be null.
	 * @param style  A style which may used for element, may be null.
	 * 
	 * @return A desired {@link CheckBox} widget.
	 */
	public static Widget createCheckBox(String title, String text, String style) {
		return createCheckBox(text, text, style, false, true);
	}
	
	/**
	 * Does create a <em>full qualified</em> {@link CheckBox}.
	 * 
	 * @param title  A title used for creation of {@link CheckBox}, may be null but should not.
	 * @param text  A text to set for element description, may be null.
	 * @param style  A style which may used for element, may be null.
	 * 
	 * @return A desired {@link CheckBox} widget.
	 */
	public static Widget createCheckBox(String title, String text, String style, boolean checked, boolean enabled) {
		CheckBox cb = new CheckBox(text);
		cb.setTitle(title);
		cb.setChecked( checked );
		cb.setEnabled(enabled);
		setWidgetProperties(cb, title, style);
		setWidgetText( cb, text );
		return cb;
	}
	
	// -------------------------- RADIOBOX SECTION ----------------------------
	/**
	 * Does create a new {@link RadioButton} element.
	 * 
	 * @param name  A name to set for radio element assignment.
	 * @param text  A text to set for element description.
	 * @param style  A style which may used for element.
	 * @param checked  Indicates standard state of box.
	 * @param enabled  Indicates weather or not a box is enabled after creation.
	 * 
	 * @return A desired {@link RadioButton} widget.
	 */
	public static RadioButton createRadioButton(String name, String text, String style, boolean checked, boolean enabled) {
		RadioButton cb = new RadioButton(name, text);
		if( null != style ) {
			cb.setStyleName( style );
		}
		cb.setChecked(checked);
		cb.setEnabled(enabled);
		return cb;
	}
	
}
